This chapter documents the tables that make up a TrueType font file, including AAT extensions to the core TrueType specification. Documentation is not included for OpenType-specific tables, even those supported on OS X and iOS. For further information on those tables, see the OpenType specification.

Table 1 describes the data types used in TrueType font files on all platforms.

With the exception of the font directory which must appear first in the font file, the tables that make up a font can appear in any order. For convenience in accessing the information presented in this chapter, tables are described in alphabetical order.

In addition to standard integer data types, the TrueType font format uses the following:

Table 1 : The 'sfnt' data types

NOTE: A shortFrac is an int16_t with a bias of 14. This means it can represent numbers between 1.999 (0x7fff) and -2.0 (0x8000). 1.0 is stored as 16384 (0x4000) and -1.0 is stored as -16384 (0xc000).

A TrueType font file consists of a sequence of concatenated tables. A table is a sequence of words. Each table must be long aligned and padded with zeroes if necessary.

The first of the tables is the font directory, a special table that facilitates access to the other tables in the font. The directory is followed by a sequence of tables containing the font data. These tables can appear in any order. Certain tables are required for all fonts. Others are optional depending upon the functionality expected of a particular font.

The tables have names known as tags. Tags have the type uint32. Currently defined tag names consist of four characters. Tag names with less than four characters have trailing spaces. When tag names are shown in text they are enclosed in straight quotes.

Tables that are required must appear in any valid TrueType font file. The required tables and their tag names are shown in Table 2.

Table 2: The required tables

Apple makes a distinction between a "TrueType font" (which refers to a particular font outline definition technology) and an "sfnt-housed font," which refers to any font which uses the same packaging format as a TrueType font: that is, it uses the same directory structure and the same table format and meaning for any tables present.

This is an important distinction, because Apple supports other varieties of sfnt-housed font on OS X and iOS, most notably bitmap-only fonts and OpenType fonts. Informally, people often refer to any sfnt-housed font as a "TrueType font," but this is strictly speaking inaccurate.

The "required" tables listed in Table 2 are only required for TrueType fonts. Other varieites of sfnt-housed font may not have them. For example, bitmap-only sfnt-housed fonts do not have an 'hmtx', 'hhea' or 'head' table. CoreText, Apple's rendering system for Unicode-encoded text, does require that any sfnt-housed font have a 'cmap' and 'name' table.

For font vendors: If you are unsure whether a particular table should be included for your non-TrueType sfnt-housed font, it is generally safe to include it, or you may contact Apple for advice.

For font users: Never assume that any particular table is present in a font on OS X. Fonts may be non-TrueType sfnt-housed fonts and lack some of TrueType's required tables. Moreover, fonts may be ill-formed and yet installed. Provide graceful error handling if a font you are using lacks a table you require.

Optional tables may be needed depending upon the functionality expected of a given font file'. The optional tables and their tag names are listed in Table 3. The 'hdmx' table is used on Macintosh platforms only. The 'OS/2' table is required for fonts that are to be used on that platform but appears in the optional table because it is not required for all TrueType font files.

Apple Advanced Typography (AAT) Tables are used with the Line Layout capability of Apple's CoreText.

Additional tables may be defined to support other platforms, such as OpenType, or to provide for future expansion. Tags for these tables must be registered. Contact Apple Developer Technical Support for information regarding the registration process. Tag names consisting of all lower case letters are reserved for Apple's use.

Table 3: The optional tables

The font directory, the first of the tables, is a guide to the contents of the font file. It provides the information required to access the data in the other tables. The directory consists of two parts: the offset subtable and the table directory. The offset subtable records the number of tables in the font and provides offset information enabling quick access to the directory tables. The table directory consists of a sequence of entries, one for each table in the font.

The offset subtable, documented in Table 4, begins with the scaler type of the font. The number of tagged tables in the 'sfnt' follows.The table directory itself and any subtables are not included in this count. The entries for searchRange, entrySelector and rangeShift are used to facilitate quick binary searches of the table directory that follows. Unless a font has a large number of tables, a sequential search will be fast enough.

If a faster search is necessary, a binary search is most easily done on a number of entries that is a power of two. This makes it possible to cut the number of items to search in half by shifting. The remaining offset subtable entries should be set as follows:

Before the search loop starts, compare the target item to the item with number rangeShift. If the target item is less than rangeShift, search from the beginning of the table. If it is greater, search starting at the item with number rangeShift.

Note that the searchRange, the entrySelector and the rangeShift are all multiplied by 16 which represents the size of a directory entry.

Table 4 : The offset subtable